Node / meshtastic / Meshtastic-Android / files / .specify / memory / constitution.md

Displaying Rendered • View raw • Download

<!--

SYNC IMPACT REPORT

Version change: 1.3.1 → 1.3.2

Modified principles:

• I–VII: Rationale blocks compressed into HTML comments (no semantic change)

Modified sections: None.

Added sections: None.

Removed sections: None.

Templates requiring updates: None (no principle renumbering).

Follow-up TODOs: None.

-->

Business logic MUST reside exclusively in T383838commonMain source sets. KMP-equivalent libraries

MUST be used in place of JVM/Android-specific APIs:

• MUST use Okio (not T383838java.io), Ktor (not T383838java.net/OkHttp in common), Mutex/atomicfu

(not T383838java.util.concurrent), Room KMP, DataStore KMP, and Koin 4.2+.

• MUST NOT import T383838java.* or T383838android.* in any T383838commonMain module.

• Platform-specific implementations belong in T383838androidMain/T383838desktopMain actual

declarations only.

<!-- Rationale: Multi-platform parity (Android, Desktop, iOS). Framework bleed in commonMain breaks compilability on non-Android targets. -->

All code contributions MUST pass static analysis before merge:

• T383838./gradlew spotlessApply MUST be run and T383838spotlessCheck MUST pass with no violations.

• T383838detekt MUST pass with no new violations introduced.

• A task or PR is considered incomplete if either check fails.

<!-- Rationale: Consistent code style and static analysis gates prevent technical debt accumulation. -->

All UI MUST use JetBrains Compose Multiplatform, not Android-only Jetpack Compose APIs:

• MUST use T383838MeshtasticNavDisplay and T383838NavigationBackHandler for navigation across all

entry points.

• Floats MUST be pre-formatted using T383838NumberFormatter.format() before display in any

composable.

• UI MUST compile and render correctly on all supported targets (Android, Compose Desktop).

<!-- Rationale: Compose Multiplatform ensures UI consistency across platforms. -->

The application handles sensitive mesh network data; user privacy MUST be protected at all

times:

• MUST NOT log or expose PII, location data, or cryptographic keys in logs, crash reports,

or any debug output.

• Secrets MUST be git-ignored and MUST NOT be committed to the repository under any

circumstances.

• T383838core/proto is a read-only upstream submodule (T383838meshtastic/protobufs). MUST NOT modify

T383838.proto files directly; proto changes require an upstream issue labeled T383838upstream.

<!-- Rationale: Meshtastic users rely on the mesh for private, off-grid communications. Data leaks could endanger users in sensitive deployments. -->

All user-facing UI MUST conform to the Meshtastic Client Design Standards:

• The canonical reference lives at:

T383838https://raw.githubusercontent.com/meshtastic/design/refs/heads/master/standards/meshtastic_design_standards_latest.md

• New screens and significant UI changes (any screen with ≥3 composables or a new

navigation destination) MUST be reviewed against the design standards before merge.

• Deviations from the design standards require explicit justification in the PR description

with a rationale for why the standard cannot or should not be followed.

• Features that affect multiple platforms (messaging, settings, telemetry, etc.) MUST

reference an existing cross-platform behavior spec in

meshtastic/design/features/,

or create one using the T383838TEMPLATE.md in that directory before writing the

Android implementation spec. Platform-specific-only features (e.g., Android widget,

Wear OS tile) may mark the T383838Cross-Platform Spec field as N/A with justification.

<!-- Rationale: Consistent cross-platform UX ensures users have a predictable experience regardless of platform. -->

In-app documentation MUST remain accurate and current as the codebase evolves.

Documentation changes propagate to three consumers — all three MUST be considered:

1. In-app docs browser — T383838syncDocsToComposeResources copies T383838docs/ into Compose

Resources at build time. Changes are bundled into the app automatically.

2. Jekyll site (GitHub Pages) — T383838docs/ is served directly. The T383838docs-deploy.yml

workflow rebuilds on push to T383838main.

3. Docusaurus site (meshtastic.org) — T383838scripts/sync-android-docs.js transforms

T383838docs/ for the external site. Runs weekly via the T383838meshtastic/meshtastic repo.

Governance rules:

• Every doc page MUST include a T383838last_updated frontmatter field (YYYY-MM-DD).

Update this field whenever page content changes.

• PRs that modify user-facing UI source files MUST update the corresponding doc page(s)

or apply the T383838skip-docs-check label with justification. The docs staleness check is a

blocking CI gate.

• Internal cross-references between doc pages and image paths MUST be validated; broken

links fail the T383838docs-governance workflow.

• Every user-facing feature module MUST have corresponding documentation in T383838docs/user/

or T383838docs/developer/. Coverage is checked by T383838scripts/check-doc-coverage.js.

• Pages older than 180 days without updates trigger an advisory freshness warning.

• New doc pages MUST be registered in T383838DocBundleLoader.kt (in-app index), and added to

the T383838KNOWN_*_SLUGS sets in T383838sync-android-docs.js (Docusaurus link resolution).

Jekyll picks up new pages automatically via T383838_config.yml scope-based defaults.

• Image references MUST use root-relative paths (T383838/assets/screenshots/filename.png) so

they resolve correctly in both Jekyll and the in-app renderer. The sync script rewrites

these to Docusaurus paths automatically.

<!-- Rationale: Documentation drift misleads users and increases support burden. Three distinct consumers means changes must be verified across all delivery channels. -->

Local verification MUST complete successfully before any T383838git push:

• MUST run T383838./gradlew spotlessApply spotlessCheck detekt plus relevant module T383838:test

tasks for all modules touched.

• After pushing, CI status MUST be confirmed via T383838gh pr checks <PR> or

T383838gh run list --branch <branch> --limit 5. Phrases like "CI should be green" are

explicitly prohibited.

<!-- Rationale: Verification is a hard gate, not an optimistic assumption. Skipped local checks are the leading cause of CI failures. -->

Non-negotiable workflow steps are defined in T383838AGENTS.md T383838<process_essentials>. Key

requirements: bootstrap before build, baseline verification before push, sort-strings after

adding resources, update T383838.agent_memory/session_context.md per session, plan complex

refactors (touching ≥3 modules or >200 LOC changed) in T383838.agent_plans/, limit context

reads to relevant modules.

The following module boundaries and technology choices are fixed for this project:

• KMP Modules: T383838core:domain (business logic), T383838core:data (repositories),

T383838core:database (Room KMP), T383838core:datastore (preferences), T383838core:network (Ktor),

T383838core:ble (Kable multiplatform BLE).

• State Management: Unidirectional Data Flow (UDF) with ViewModels, Kotlin Coroutines,

and Flow. No reactive frameworks other than Coroutines/Flow in T383838commonMain.

• Dependency Injection: Koin 4.2+ with Koin Annotations and the K2 Compiler Plugin.

No alternative DI framework may be introduced.

• Navigation: JetBrains Navigation 3 for multiplatform routing with RESTful deep

linking. All navigation MUST use T383838MeshtasticNavDisplay.

• Data Protocol: Protobuf for device communications (read-only upstream submodule).

Room KMP for local persistence. DataStore for user preferences.

• Language & Toolchain: Kotlin 2.3+ targeting JDK 21. Java source files MUST NOT be

introduced in KMP modules.

The following coding standards are enforced by contextual instruction files

(T383838.github/instructions/) scoped to relevant source sets. They are acknowledged by this

constitution but defined and maintained in their respective files:

• T383838safeCatching {} over T383838runCatching {} in coroutine/suspend contexts

• T383838org.meshtastic.core.common.util.ioDispatcher over T383838Dispatchers.IO

• T383838MeshtasticIcons (from T383838core/ui/icon/) over T383838material.icons.Icons

• T383838MetricFormatter for display strings (temperature, voltage, percent, signal)

• T383838stringResource(Res.string.key) with T383838python3 scripts/sort-strings.py after additions

• T383838kotlinx.coroutines.CancellationException (not T383838kotlin.coroutines.cancellation.*)

• Branch naming: T383838feat/, T383838fix/, T383838chore/, T383838docs/, T383838build/, T383838ci/, T383838refactor/,

T383838test/, T383838deps/, or numeric spec prefix; always off T383838origin/main

This constitution is the canonical governance document and supersedes all other practices,

coding guidelines, and agent instructions. T383838AGENTS.md is the agent-facing operational

summary derived from this constitution. The files T383838.github/copilot-instructions.md,

T383838CLAUDE.md, and T383838GEMINI.md MUST redirect to T383838AGENTS.md and MUST NOT diverge from it.

Amendment Procedure:

1. Propose the amendment with rationale and a migration plan in a PR description.

2. Update T383838AGENTS.md and this constitution atomically in the same commit.

3. Update all downstream references in the same commit:

• T383838.skills/speckit/SKILL.md (principle count and descriptions)

• T383838.specify/templates/checklist-template.md (checklist items)

• T383838.specify/templates/plan-template.md (Constitution Check section)

• The SYNC IMPACT REPORT comment at the top of this file

4. Increment T383838CONSTITUTION_VERSION per the versioning policy below.

5. All PRs and code reviews MUST verify compliance with the current constitution version.

Versioning Policy:

• MAJOR: Backward-incompatible principle removal or fundamental redefinition.

• MINOR: New principle or section added, or materially expanded guidance.

• PATCH: Clarifications, wording fixes, or non-semantic refinements.

Compliance Review: Every implementation plan and PR description MUST include a

Constitution Check confirming all seven principles were evaluated. Complexity violations

require explicit justification in the Complexity Tracking table of the plan document.

Version: 1.3.2 | Ratified: 2026-05-07 | Last Amended: 2026-05-21